home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / lib / perl5 / Glib / version.pod < prev    next >
Text File  |  2009-04-29  |  6KB  |  215 lines
  1. =head1 NAME
  2.  
  3. Glib::version -  Library Versioning Utilities
  4.  
  5. =cut
  6.  
  7. =for position SYNOPSIS
  8.  
  9. =head1 SYNOPSIS
  10.  
  11.   # require at least version 1.021 of the Glib module
  12.   use Glib '1.021';
  13.  
  14.   # g_set_application_name() was introduced in GLib 2.2.0, and
  15.   # first supported by version 1.040 of the Glib Perl module.
  16.   if ($Glib::VERSION >= 1.040 and Glib->CHECK_VERSION (2,2,0)) {
  17.      Glib::set_application_name ('My Cool Program');
  18.   }
  19.  
  20. =for position DESCRIPTION
  21.  
  22. =head1 DESCRIPTION
  23.  
  24. Both the Glib module and the GLib C library are works-in-progress, and 
  25. their interfaces grow over time.  As more features are added to each, 
  26. and your code uses those new features, you will introduce 
  27. version-specific dependencies, and naturally, you'll want to be able to 
  28. code around them.  Enter the versioning API.
  29.  
  30. For simple Perl modules, a single version number is sufficient; 
  31. however, Glib is a binding to another software library, and this 
  32. introduces some complexity.  We have three versions that fully specify 
  33. the API available to you.
  34.  
  35. =over
  36.  
  37. =item Perl Bindings Version
  38.  
  39. Perl modules use a version number, and Glib is no exception.  
  40. I<$Glib::VERSION> is the version of the current Glib module.  By ad hoc 
  41. convention, gtk2-perl modules generally use version numbers in the form 
  42. x.yyz, where even yy values denote stable releases and z is a 
  43. patchlevel.
  44.  
  45.    $Glib::VERSION
  46.    use Glib 1.040; # require at least version 1.040
  47.  
  48. =item Compile-time ("Bound") Library Version
  49.  
  50. This is the version of the GLib C library that was available when the 
  51. Perl module was compiled and installed.  These version constants are 
  52. equivalent to the version macros provided in the GLib C headers.  GLib 
  53. uses a major.minor.micro convention, where even minor versions are 
  54. stable.  (gtk2-perl does not officially support unstable versions.)
  55.  
  56.    Glib::MAJOR_VERSION
  57.    Glib::MINOR_VERSION
  58.    Glib::MICRO_VERSION
  59.    Glib->CHECK_VERSION($maj,$min,$mic)
  60.  
  61. =item Run-time ("Linked") Library Version
  62.  
  63. This is the version of the GLib C library that is available at run 
  64. time; it may be newer than the compile-time version, but should never 
  65. be older.  These are equivalent to the version variables exported by 
  66. the GLib C library.
  67.  
  68.    Glib::major_version
  69.    Glib::minor_version
  70.    Glib::micro_version
  71.  
  72. =back
  73.  
  74. =head2 Which one do I use when?
  75.  
  76. Where do you use which version?  It depends entirely on what you're 
  77. doing.  Let's explain by example:
  78.  
  79. =over
  80.  
  81. =item o Use the Perl module version for bindings support issues
  82.  
  83. You need to register a new enum for use as the type of an object 
  84. property.  This is something you can do with all versions of the 
  85. underlying C library, but which wasn't supported in the Glib Perl 
  86. module until $Glib::VERSION >= 1.040.
  87.  
  88. =item o Use the bound version for library features
  89.  
  90. You want to call Glib::set_application_name to set a human-readable name
  91. for your application (which is used by various parts of Gtk2 and Gnome2).
  92. g_set_application_name() (the underlying C function) was added in version
  93. 2.2.0 of glib, and support for it was introduced into the Glib Perl module
  94. in Glib version 1.040.  However, you can build the Perl module against any
  95. stable 2.x.x version of glib, so you might not have that function available
  96. even if your Glib module is new enough!
  97.   Thus, you need to check two things to see if the this function is 
  98. available:
  99.  
  100.    if ($Glib::VERSION >= 1.040 && Glib->CHECK_VERSION (2,2,0)) {
  101.        # it's available, and we can call it!
  102.        Glib::set_application_name ('My Cool Application');
  103.    }
  104.  
  105. Now what happens if you installed the Perl module when your system had 
  106. glib 2.0.6, and you upgraded glib to 2.4.1?  Wouldn't g_set_application_name() 
  107. be available?  Well, it's there, under the hood, but the bindings were 
  108. compiled when it wasn't there, so you won't be able to call it! 
  109. That's why we check the "bound" or compile-time version.  By the way, to 
  110. enable support for the new function, you'd need to reinstall (or upgrade)
  111. the Perl module.
  112.  
  113. =item o Use the linked version for runtime work-arounds
  114.  
  115. Suppose there's a function whose API did not change, but whose 
  116. implementation had a bug in one version that was fixed in another 
  117. version.  To determine whether you need to apply a workaround, you 
  118. would check the version that is actually being used at runtime.
  119.  
  120.    if (Glib::major_version == 2 &&
  121.        Glib::minor_version == 2 &&
  122.        Glib::micro_version == 1) {
  123.       # work around bug that exists only in glib 2.2.1.
  124.    }
  125.  
  126. In practice, such situations are very rare.
  127.  
  128. =back
  129.  
  130. =cut
  131.  
  132.  
  133.  
  134. =for object Glib::version Library Versioning Utilities
  135. =cut
  136.  
  137.  
  138.  
  139.  
  140. =head1 METHODS
  141.  
  142. =head2 boolean = Glib-E<gt>B<CHECK_VERSION> ($required_major, $required_minor, $required_micro)
  143.  
  144. =over
  145.  
  146. =item * $required_major (integer) 
  147.  
  148. =item * $required_minor (integer) 
  149.  
  150. =item * $required_micro (integer) 
  151.  
  152. =back
  153.  
  154. Provides a mechanism for checking the version information that Glib was
  155. compiled against. Essentially equvilent to the macro GLIB_CHECK_VERSION.
  156.  
  157. =head2 (MAJOR, MINOR, MICRO) = Glib->B<GET_VERSION_INFO>
  158.  
  159. Shorthand to fetch as a list the glib version for which Glib was compiled.
  160. See C<Glib::MAJOR_VERSION>, etc.
  161.  
  162. =head2 integer = Glib::MAJOR_VERSION 
  163.  
  164. Provides access to the version information that Glib was compiled against.
  165. Essentially equivalent to the #define's GLIB_MAJOR_VERSION.
  166.  
  167. =head2 integer = Glib::MICRO_VERSION 
  168.  
  169. Provides access to the version information that Glib was compiled against.
  170. Essentially equivalent to the #define's GLIB_MICRO_VERSION.
  171.  
  172. =head2 integer = Glib::MINOR_VERSION 
  173.  
  174. Provides access to the version information that Glib was compiled against.
  175. Essentially equivalent to the #define's GLIB_MINOR_VERSION.
  176.  
  177. =head2 integer = Glib::major_version 
  178.  
  179. Provides access to the version information that Glib is linked against.
  180. Essentially equivalent to the global variable glib_major_version.
  181.  
  182. =head2 integer = Glib::micro_version 
  183.  
  184. Provides access to the version information that Glib is linked against.
  185. Essentially equivalent to the global variable glib_micro_version.
  186.  
  187. =head2 integer = Glib::minor_version 
  188.  
  189. Provides access to the version information that Glib is linked against.
  190. Essentially equivalent to the global variable glib_minor_version.
  191.  
  192.  
  193.  
  194. =cut
  195.  
  196.  
  197. =head1 SEE ALSO
  198.  
  199. L<Glib>
  200.  
  201.  
  202. =cut
  203.  
  204.  
  205. =head1 COPYRIGHT
  206.  
  207. Copyright (C) 2003-2009 by the gtk2-perl team.
  208.  
  209. This software is licensed under the LGPL.  See L<Glib> for a full notice.
  210.  
  211.  
  212.  
  213. =cut
  214.  
  215.